offers: add used_count to listoffers by alexgrad42 · Pull Request #9162 · ElementsProject/lightning

alexgrad42 · 2026-05-21T19:33:01Z

This adds a new 'used_count' field to the 'listoffers' RPC command output to see the exact number of times a BOLT12 offer has been paid by counting associated settled invoices.

Changelog-Added: add a new 'used_count' field to the 'listoffers' RPC command

Closes #9146

This adds a new 'used_count' field to the 'listoffers' RPC command output to see the exact number of times a BOLT12 offer has been paid by counting associated settled invoices. Changelog-Added: add a new 'used_count' field to the 'listoffers' RPC command Closes ElementsProject#9146

nGoline

Great addition. This fills a real gap and the implementation is straightforward, the core idea is solid and it's close to being mergeable.
A few things to fix before we can land this.

nGoline · 2026-05-22T16:58:36Z

 				json_populate_offer(response,
 						    &id, b12,
 						    label, status, force_paths);
+				u64 used_count = wallet_offer_count_payments(wallet, offer_id);


You're passing offer_id instead of &id here. Since we're inside the else block (meaning offer_id was not provided), this would pass NULL to a function annotated with NON_NULL_ARGS(1,2), so every offer in the list-all path would get a count of 0 (or worse).
Should be &id.

nGoline · 2026-05-22T16:58:41Z

+u64 wallet_offer_count_payments(struct wallet *w,
+				const struct sha256 *offer_id);
+	NON_NULL_ARGS(1,2);


You should remove the ; between the function declaration and NON_NULL_ARGS.

Suggested change

u64 wallet_offer_count_payments(struct wallet *w,

const struct sha256 *offer_id);

NON_NULL_ARGS(1,2);

u64 wallet_offer_count_payments(struct wallet *w,

const struct sha256 *offer_id)

NON_NULL_ARGS(1,2);

nGoline · 2026-05-22T17:04:40Z

+					"  AND state = 1;")); 
+
+	db_bind_sha256(stmt, offer_id);


The hardcoded 1 is fragile and doesn't self-document intent. We have a enum constant for PAID.

Suggested change

" AND state = 1;"));

db_bind_sha256(stmt, offer_id);

" AND state = ?;"));

db_bind_sha256(stmt, offer_id);

db_bind_int(stmt, invoice_status_in_db(PAID));

nGoline · 2026-05-22T17:05:31Z

 						    &id, b12,
 						    label, status, force_paths);
+				u64 used_count = wallet_offer_count_payments(wallet, offer_id);
+		    	        json_add_u64(response, "used_count", used_count);


The indentation here is inconsistent with a mix of spaces and tabs. Please align it with the surrounding code (tabs only).

nGoline · 2026-05-22T17:07:56Z

            "deprecated": null
        },
+        "ListOffers.offers[].used_count": {
+            "added": "pre-v0.10.1",


pre-v0.10.1 is reserved for fields that existed before versioning was introduced. This is a new field, so it needs the correct release tag. There's no time to include it in v26.06, so let's target the next one: v26.09.

nGoline · 2026-05-22T17:16:39Z

          "required": [
            "offer_id",
            "active",
            "single_use",
            "force_paths",
            "bolt12",
            "used"
          ],


used_count is always computed and returned unconditionally, so it should be listed in the required array of the items object in this schema.

nGoline · 2026-05-22T17:21:08Z

+	stmt = db_prepare_v2(w->db, SQL("SELECT COUNT(*)"
+					"  FROM invoices"
+					"  WHERE local_offer_id = ?"
+					"  AND state = 1;")); 


This executes one SELECT COUNT(*) per offer, which means a node with 1000 offers will fire 1001 queries on every listoffers call. Consider computing all counts in a single query with GROUP BY local_offer_id, then looking up each offer's count from the result.

nGoline · 2026-05-22T17:28:20Z

+	stmt = db_prepare_v2(w->db, SQL("SELECT COUNT(*)"
+					"  FROM invoices"
+					"  WHERE local_offer_id = ?"
+					"  AND state = 1;")); 


Trailing whitespace: make check-source will catch this. Please remove the space after ));..

nGoline · 2026-05-22T17:41:20Z

 						    &id, b12,
 						    label, status, force_paths);
+				u64 used_count = wallet_offer_count_payments(wallet, offer_id);
+		    	        json_add_u64(response, "used_count", used_count);


You're adding this field between json_populate_offer() output and description. Consider moving it after description so the JSON output is consistent between versions.

nGoline · 2026-05-22T17:53:01Z

+    assert 'used_count' in offers[0], "Error: used_count field is missing from listoffers response!"
+    assert offers[0]['used_count'] == 0


Let's drop the custom message string. The in check is redundant since the == 0 assertion on the next line would already produce a KeyError if the key were missing. Plain assert is the project convention here.

Suggested change

assert 'used_count' in offers[0], "Error: used_count field is missing from listoffers response!"

assert offers[0]['used_count'] == 0

assert offers[0]['used_count'] == 0

nGoline · 2026-05-22T17:56:30Z

Please rebase onto master instead of merging it in. Merging master into your feature branch creates a noisy history and makes the diff harder to follow. A clean rebase keeps the commits linear and makes it easier to bisect if something goes wrong later

nGoline · 2026-05-22T17:58:02Z

Please rebase onto master instead of merging it in. Merging master into your feature branch creates a noisy history and makes the diff harder to follow. A clean rebase keeps the commits linear and makes it easier to bisect if something goes wrong later

Also, when addressing the review feedback, please use fixup! commits (or git commit --fixup=<sha>) rather than separate "fix" commits. Having a commit like "fix indentation" or "address review comments" in the final history makes it harder to bisect.

alexgrad42 requested a review from cdecker as a code owner May 21, 2026 19:33

alexgrad42 force-pushed the feature/add_offer_used_count branch from 85af710 to e3719b3 Compare May 21, 2026 20:45

alexgrad42 force-pushed the feature/add_offer_used_count branch from e3719b3 to 5370032 Compare May 21, 2026 20:50

Merge branch 'master' into feature/add_offer_used_count

9aaff58

nGoline requested changes May 22, 2026

View reviewed changes

		assert 'used_count' in offers[0], "Error: used_count field is missing from listoffers response!"
		assert offers[0]['used_count'] == 0

Conversation

alexgrad42 commented May 21, 2026

Uh oh!

nGoline left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nGoline commented May 22, 2026

Uh oh!

nGoline commented May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants